Programming Sound Cards

home *** CD-ROM | disk | FTP | other *** search

/ Programming Sound Cards / Programming Sound Cards.iso / sound_16 / cd-box.doc < prev next >

Wrap

Text File | 1995-01-01 | 106KB | 2,693 lines

CD-Box(TM) v3.03 User's manual If you're viewing this from CD-Box, press C to display the table of contents, P to jump to a specific page, and the arrow keys to move around. Press Esc anytime to return to CD-Box. This documentation has been compressed to cut down on archive size and transmission time and costs. Some chapters have been removed or condensed. It is nevertheless more than enough for normal use; nothing vital is missing. The full documentation is included on the registration disk (see page 38). (C) Jeffrey Belt, 1993 All rights reserved _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER "Jeffrey Belt is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442- 9427 USA, FAX 616-788-2765 or send a Compuserve message via CompuServe Mail to ASP Ombudsman 70007,3536" CD-Box v3.03 Page 5 CD-BOX V3.03 TABLE OF CONTENTS A. INTRODUCTION ......................................................7 1. If the meaning of a word escapes you... ......................7 2. What CD-Box is ...............................................7 B. INSTALLATION ......................................................9 1. First time around (quick start) ..............................9 2. Complete installation ........................................9 C. HOW TO USE CD-BOX .................................................11 1. Let's start with the basics ..................................11 2. Select mode ..................................................11 3. Play mode ....................................................12 4. Modify mode ..................................................13 5. Goto mode ....................................................14 6. Files mode ...................................................14 7. Debug mode ...................................................14 D. HOW CD-BOX WORKS ..................................................16 1. Programs you need for each format ............................16 2. Adding and removing songs ....................................17 3. Saving memory ................................................18 4. How CD-Box plays songs .......................................18 5. Details on .ARC, .ARJ, .PAK and .ZIP archives ................19 a. When does CD-Box uncompress the songs stored in archives? ..........................................19 b. Where are files exploded to? ............................19 c. What programs are necessary to take full advantage of this feature? ...................................19 6. Dual support .................................................20 E. KEYBOARD COMMANDS .................................................21 F. CD-BOX.CFG ........................................................22 1. The purpose of CD-BOX.CFG ....................................22 2. Syntax .......................................................22 a. Comments ................................................22 b. Parameter settings ......................................22 c. Section identifiers .....................................23 3. Command reference ............................................23 a. System parameters .......................................23 b. Archiver parameters .....................................24 c. External drivers and players ............................25 d. Support for other song formats ..........................27 G. ADVANCED USE ......................................................28 1. Command-line parameters ......................................28 H. TROUBLE-SHOOTING ..................................................30 1. Common problems ..............................................30 a. Crashes during song analysis ............................30 b. Refusal to play certain songs ...........................30 c. Trouble with .MODs ......................................32 d. Hardware trouble ........................................33 2. Debugging switch /D ..........................................34 I. REGISTERING CD-BOX ................................................38 1. What is shareware? ...........................................38 2. Why register? ................................................38 3. How to register CD-Box .......................................39 4. Support ......................................................40 5. Bugs? What bugs? .............................................40 6. Viruses and similar nasty programs ...........................41 J. GLOSSARY ..........................................................42 K. EXTERNAL DRIVERS AND PLAYERS ......................................45 L. TECHNICAL NOTES ...................................................46 1. A word on files ..............................................46 2. Sound formats ................................................46 M. THANKS ............................................................47 CD-Box v3.03 Page 6 N. LICENSE & ABSENCE OF WARRANTY .....................................48 1. Disclaimer ...................................................48 2. Trial use license ............................................48 3. Permanent license ............................................48 CD-Box v3.03 Page 7 A. INTRODUCTION ___________________________________________ 1. If the meaning of a word escapes you... .... then don't hesitate to peek at the glossary (page 42). You'll find explanations on DOS functions that CD-Box uses (which may be useful to inexperienced users), and the definition of terms more specific to CD- Box. In any case, don't worry. CD-Box is very simple to use, and this documentation tries to be clear too! __________________ 2. What CD-Box is CD-Box is, stated simply, a program which plays back music files of various formats on the AdLib Music Synthetizer Card and the SoundBlaster card. It offers a common interface, somewhat like a jukebox, whatever the format. CD-Box treats all the same way. Moreover, it is also very pretty and fun to use - it runs in 256 colors and can use your mouse. CD-Box's main features: o A pretty interface and fun animation: CDs pop up and down and start and stop spinning, pages scroll... including random events I'll let you discover! o Support for .CMF, .MID, .MOD, .MUS, .ROL, .VOC, .WAV (.CMF, .MOD, .VOC and .WAV files work with SoundBlaster only) and any other format you define in multiple drives and directories. These files can also be stored in .ARC, .ARJ, .PAK and/or .ZIP archives to save disk space CD- Box will find them and play them from the archive (using a RAM drive if you want). .MOD, .VOC and .WAV also have volume control, skipping backward and forward within the song, and echo effects. o CD-Box allows you to easily program a selection of songs; it waits for you to select the songs you want to hear before starting to play the first one. o Instead of selecting songs, you can tell CD-Box how long you want the playback to last, and it will automatically select songs for you. You can even do that from the DOS command line (or a batch file), and CD- Box will play the songs, then exit right back to DOS. o CD-Box makes it easy to choose files in which to pick songs so if you compressed your songs by category, you can tell CD-Box which categories to use! o No data file to keep to date; bank filenames and song titles can be modified directly from CD-Box, which will save your changes to disk. CD-Box also knows the titles and lengths of numerous songs, and when it encounters unknown songs, can sometimes (it depends on the format) extract data from the files on disk. CD-Box v3.03 Page 8 o CD-Box can use EMS and XMS to some extent, and is able to examine the SOUND environment variable and of loading drivers and player programs from there if necessary (as any good SoundBlaster software should do). CD-Box v3.03 Page 9 B. INSTALLATION ________ Hardware You must have a VGA display and an AdLib or SoundBlaster card (or better) - a hard disk and a mouse are also highly recommended. ___________________________________ 1. First time around (quick start) If you want to try CD-Box quickly, create a directory, extract all the files from CDBOX303 into this directory, type RUNME, and press Enter. _________________________ 2. Complete installation This part gives more details on the installation, and gives hints on what you have to for CD-Box to play ALL song formats. __________________ Create a directory I suggest CD-BOX, but you are free to use another name. Go to the (future) parent directory and type: MKDIR CD-BOX Then go to the created directory: CHDIR CD-BOX _____________________ Put in this directory o the files CD-BOX.EXE and CD-BOX.CFG. o all music files you can find (files with the extension .CMF, .MID, .MOD, .MUS, .ROL, .VOC and .WAV). Instead of using the files themselves, you can put archives (.ARC, .ARJ, .PAK and/or .ZIP) which contain these files. Putting in the directory the files AGNES.CMF, DOODLE.CMF and WIPE_OUT.CMF is the same as putting in the directory an archive called (for instance) CMF.ZIP which contains AGNES.CMF, DOODLE.CMF and WIPE_OUT.CMF. You don't have to put all your songs files in this directory; CD-Box can look for them elsewhere on the disk (and even on other disks) if you want it to. I'll tell you more about this later. _________ Make sure CD-Box v3.03 Page 10 o that the BLASTER environment variable is set (see page 42). It is not mandatory, but it might help; skip this step for now, and return to it later if you have trouble with .VOC and .WAV files. o that the "archivers" (by default: ARCE.COM, ARJ.EXE, PAK.EXE and PKUNZIP.EXE) also are on the PATH. You can skip this step if you didn't compress song files in .ARC, .ARJ, .PAK or .ZIP archives. ____ Load the SBFMDRV and SOUND drivers in memory (if you have them). Just type their names at the DOS prompt (see page 18 if you're concerned about saving memory). ___________ Type CD-Box ...and press Enter (the first time CD-Box is run, the directory scan may take a long time, especially if you have many songs - don't worry, it will go much faster next time). If you didn't put your songs in CD-Box's directory, you can type on the command line the specifications of the files to analyse, and add /s to scan subdirectories also. For instance, if you type: cd-box a: d:\music\ /s CD-Box will scan and load all songs in A: and D:\MUSIC\, and all their subdirectories. ________ Have fun ...and see what CD-Box can do. If you get errors or have trouble, see page 30. If you want to know exactly what you have to do for CD-Box to play ALL formats, see page 16. If you have other players or archivers than those mentioned above, check out CD-BOX.CFG; if you don't get it all, see page 22. If you use CD-Box, register! See page 38. And now, let's relax... CD-Box v3.03 Page 11 C. HOW TO USE CD-BOX _______________________________ 1. Let's start with the basics The explanations below, as with most of this documentation, supposes you have a mouse and CD-Box is able to use it. If you use the keyboard, see page 21. You run it by typing CD-BOX at the DOS prompt. Obvious, really. If all goes well, the title page zooms by, and the main screen appears. The screen is a jukebox of sorts, with song titles in the middle. Below these is a set of big buttons, with which you can give instructions to CD-Box. The row of thinner buttons, still lower, are used to change modes; CD-Box is divided in several modes, with a set of buttons each to match - but we'll come back to that later. The digital display, which usually displays the time of day, can also display something else, depending on the active mode. When CD-Box is ready to receive your instructions, the mouse pointer is a yellow arrow. o If you start to get a little lost, press Esc repeatedly until you get back to the mode you are in when CD-Box starts up; you can then start all over again. If you press Esc again, CD-Box tells you that to quit, you need to press E. To quit CD-Box, press E, or click on "Eject". o On-line help is available from most screens by clicking Help (or pressing F1), and this very manual can be displayed by clicking Manual (or pressing F2). If you just started up CD-Box, you are in... _______________ 2. Select mode In this mode, you choose and start to play songs. The song titles loaded by CD-Box are displayed eight by eight, in the middle of the screen. o Move between the pages by clicking on the "Rewind" and "Forward" buttons (you can hold down these buttons with the mouse). Pressing the RIGHT mouse button on "Rewind" and "Forward" brings you to the first and last page, respectively. o Select one or more songs to play by clicking on the small button next to the songs' names; they will be played back in the order you selected them. The digital display changes color and displays the total time of your selection. o Click on "Loop" if you want your selection to be played over and over again. o Click on "Play" to play the songs you'll be in Play mode (see below). CD-Box v3.03 Page 12 o Clicking on "Random" brings you into Random mode. You can then select the total playing time you wish, by pressing the "Rewind" and "Forward" buttons; pressing the RIGHT mouse button brings up the minimum and maximum playing time, respectively. Once the desired time is displayed on the digital display, click on "Play". CD-Box will randomly select additional songs until the desired time is reached, then play the songs(1). o Clicking on "Random" while in Random mode, exits Random mode. o Clicking on the wide "Unselect" button will unselect ALL the songs. o Finally, click on "Eject" to quit. When you click on "Play", CD-Box switches to... _____________ 3. Play mode This mode is active while songs are being played back. Each song is played in turn, and unselected, unless "Loop" is pressed, in which case it will be reselected to be played again later. o Each song is played in turn, and then de-selected, unless "Loop" is in the down position, in which case they are reselected to be played again later. o Pressing Esc while a song is playing interrupts the current song, and CD-Box starts looking for the next one. If you press Esc between songs, playback stops entirely (songs not yet played remain selected). You've got to press Esc twice quite fast to stop the playback in fast mode (/F, see below). If CD-Box uses its own routines to play the format (I call this "internal support", we'll go into this in more detail later on), the clock displays a real-time chronometer, and the following buttons are displayed: o Stop: stops playback entirely (same as pressing Esc between songs). o Skip: interrupts the current song (same as pressing Esc while playing). o Pause: toggle it once to pause the music, and toggle it again to have it pick up where it left off. 1 Certain songs may be of unknown length (they were not known to CD- Box and they have never been played yet). When such a song is selected, CD-Box supposes the length is zero. Therefore, if you use the "Random" button and such songs are chosen, the actual playing time may be far longer than the playing time you entered (remember in such cases that Esc still works). Of course a way to compute all playing times is to use Random mode and choose the maximum playing time, in which case all songs will be played. CD-Box v3.03 Page 13 o Again: if pressed, the song being played back will be played again when the end is reached or if Skip is pressed. o Rem.: if pressed, the digital display shows the time left until the song or the total selection ends (see next button), as far as CD-Box can tell; if not, the digital display shows the time elapsed since the beginning of the song or the total selection. o Total: if pressed, the digital display shows the time elapsed or left (see previous button) for the current song; if not, it shows the time elapsed or left for the whole selection. Got it? Depending on the format, you may also have access to some or all of the following extra controls: o Volume control: press a button in the colored row to select the volume. Volumes changes are not instantaneous (some .MOD files sometimes sound weird while the volume is being changed). The higher the volume, the better the quality. o Skipping backward/forward within the song: press the button to the left of the volume control or the one to the right. CD-Box will "skip" a little of the song in either way. Trying to skip back the beginning of the song restarts the song, and trying to skip past the end stops it. o Echo-/Echo+: one press on each of these buttons decreases and increases the echo delay one step. There are five delay steps, ranging from no echo at all to a long echo, somewhat like airport announcements, if you see what I mean. Echo controls are great when used on digitized voices. Play mode switches back to Select mode when playback ends. _______________ 4. Modify mode This mode is used to modify song titles, and instruments files (bank files) linked with songs in certain formats (.MUS and .ROL). The song files themselves are not modified; CD-Box keeps the data for its own use only, and saves it in the SONGS.DAT file. Click on the wide "Modify..." button to enter Modify mode. All the songs will be unselected, and the row of buttons will flip and reveal another set of buttons. "Rewind" and "Forward" work the same as before. o You can display the song titles, bank files or filename by clicking on one of the three buttons at the right. o If you click on the small button next to a song, a dot cursor will appear and you will be able to modify whatever is displayed, using the keyboard (Backspace, Enter and Escape do the obvious things). Any changes you type in will be automatically saved to disk once you exit CD- Box. CD-Box v3.03 Page 14 _____________ 5. Goto mode This mode is used to jump quickly to a specific title (or file) by giving the first letter, instead of moving through the whole list using "Rewind" and "Forward". Click on "Goto...", and an alphabetic set of buttons will appear. From there, simply choose a letter, and CD-Box will "Rewind" or "Forward" directly to the page containing the first song starting by the letter you selected, and flash that song briefly. If no such song exists, CD-Box tries with the next letter, and the next, and may finally give up by giving an error message. When you exit Goto mode, either automatically, or by clicking on "Goto..." a second time, you will be brought back to the same mode you were in before entering Goto mode. Goto is accessible from all modes. ______________ 6. Files mode Click on "Files...", and CD-Box will save any changes you have made (bank files, song titles, whatever), and promptly forget all the songs in memory. Files names will then be displayed instead of song titles. These files are NOT the song files themselves, but the files CD-Box scanned to get the songs in memory - the difference is that archive files (.ARC, .ARJ, .PAK and .ZIP) will be displayed as such, instead of having a separate entry for each file in the archive (as is the case in Modify mode when the "File" button is pressed). Also, if the files scanned are in other drives or directories, the whole path (or as much as can fit in) is displayed. All files are selected by default. You can browse through the list using "Rewind" and "Forward" as usual, and "Goto..." a specific filename... and when you click on "Rescan", CD-Box will rescan ONLY the files left selected. Thus, if you left all the files selected, CD-Box will reload all the songs and nothing will be changed. If you unselected them all, CD-Box will load no songs. This serves as a "filter" for the songs displayed in CD-Box, and used by (for instance) Random mode. If your songs are archived by category, switching to Files mode and choosing only certain files will tell CD-Box to display and use only the songs in these categories. If you don't use archives at all, then probably Files mode will not be of much use to you. Note that the files displayed are not all the files in the directory, but rather those that contain songs. Also, if you specified /L at startup, any unplayable files in the directory will not be displayed. And, if you specified file specifications at startup (for instance, CD-BOX *.MOD Z*.ZIP), only the files matching these specifications will be displayed. All this is cumulative, of course. The command line serves as a first filter, and Files mode then enables you to choose the filtered files by hand. Files mode is much simpler to use than to describe, believe me... try it! ______________ 7. Debug mode This is not really a mode in the sense of those described above, but is a command-line switch important enough to be included here. Typing CD- BOX/D at the DOS prompt: o returns the registration number (if any!). o checks the CD-BOX.CFG file for errors, reporting any, so you can correct them. CD-Box v3.03 Page 15 o displays, for each driver, player, and archive manager, whether it was found or not. o scans the directory for songs, displaying each song name in turn, so you may find which song exactly makes CD-Box crash (if any). This mode is described in detail page 34. CD-Box v3.03 Page 16 D. HOW CD-BOX WORKS _____________________________________ 1. Programs you need for each format In addition to CD-BOX.EXE (the program) and CD-BOX.CFG (the configuration file), you need songs to play, and a player program in some cases. Those quoted below are the defaults; see page 22 to see how to change them. In a nutshell, here is the complete list of the different formats supported by CD-Box and the programs necessary to use these formats. How to obtain these drivers and players is described page 45. ________ ARCHIVES _____________ .ARC archives You need ARCE.COM, or ARC.EXE if you make a few changes in CD-BOX.CFG. _____________ .ARJ archives You need ARJ.EXE. _____________ .PAK archives You need PAK.EXE. _____________ .ZIP archives You need PKUNZIP.EXE, or UNZIP.EXE if you make a few changes in CD- BOX.CFG. _____________ MUSIC FORMATS ____________________________________ Creative Music (.CMF) (SoundBlaster) You need the sound driver SBFMDRV.COM from Creative Labs, Inc, and it has to be loaded in memory before CD-Box is run. (You can remove it by typing SBFMDRV /U once you exit CD-Box). No other program is necessary, .CMF routines are programmed directly into CD-Box. ________________________________________ Single track MIDI (.MID) (SoundBlaster?) You need FORMER.EXE - if you can find it. I know quiet .MID players are difficult to come by. Anyway, I have hopes of implementing routines in CD-Box itself. CD-Box v3.03 Page 17 _______________________________ Amiga MOD (.MOD) (SoundBlaster) You need nothing except lots of memory; CD-Box is linked to internal .MOD playing routines. ___________________________________ Music (.MUS) (AdLib & SoundBlaster) You need PLAY.EXE. Each .MUS file also needs a .SND bank file, so be sure to put them in the directory too. (ex: AGNES.MUS and AGNES.SND, MULL.MUS and MULL.SND...)(2). ____________________________________ ROLand (.ROL) (AdLib & SoundBlaster) You need the sound driver SOUND.COM from AdLib, Inc, or SB-SOUND.COM, and it has to be loaded in memory before CD-Box is run. No other program is necessary, .ROL routines are programmed directly into CD- Box. On the other hand, .ROL files also need at least one bank file, usually STANDARD.BNK or BNK974.BNK. ________________________________________ SoundBlaster VOiCe (.VOC) (SoundBlaster) You need nothing; CD-Box is able to play .VOC by itself, and is even able to find your SoundBlaster by itself (autodetection). However, setting the BLASTER environment variable might help (see page 42). Digitized sounds in other formats (Macintosh .SND, Sun .AU and many others) can be converted to .VOC using various utilities. I use and recommend SOX (maintained by Lance Norskog), available at garbo.uwasa.fi in pc/sound. ______________________________________ Windows 3.1 WAVe (.WAV) (SoundBlaster) Exactly the same as above. CD-Box treats .VOC and .WAV very similarly. The program files do not have to reside in CD-Box's directory, but make sure CD-Box has access to them (through a PATH statement for instance). CD-Box also examines the SOUND environment variable and is able to load drivers and players from there if necessary. To see if CD-Box detects properly your drivers and player programs, type CD-BOX/D at the DOS prompt. _____________________________ 2. Adding and removing songs The song titles displayed in CD-Box depend entirely on the songs found in the files present in all directories scanned at startup (either in archives or not). If you want to add songs to CD-Box, simply put them in the current directory. To remove them, delete the files. In other words, 2 .MUS bank files (.SND files) are different from Macintosh raw sound files (.SND extension also) - the former contain instrument data and the latter a complete digitized sound. CD-Box v3.03 Page 18 CD-Box always reflects the current directory - only the file names are replaced by song titles. _________________ 3. Saving memory The two drivers CD-Box uses, SBFMDRV and SB-SOUND, take up memory. There are two ways to avoid this: o If you have a 386 or better, when you load a driver, type LOADHIGH before typing the driver's name in the DOS prompt. This will load the driver in high memory, out of the critical 640K DOS memory, and CD-Box will have more memory to run. o Once you quit CD-Box, you can remove the drivers from memory by typing SBFMDRV/U and SB-SOUND/U. If you loaded them using LOADHIGH, remove them by typing LOADHIGH SBFMDRV/U and LOADHIGH SB-SOUND/U. Note that you have to remove drivers in the reverse order in which you loaded them. This does not work with AdLib's SOUND driver. See the RUNME.BAT file for an example of both these features. __________________________ 4. How CD-Box plays songs It depends on the format. As a general rule, there are two possibilities: either it plays them by itself, using its own code (internal support), or it doesn't know how to play this format, and executes an external program (the player), specific to each format. CD-Box currently provides for all formats except .MID and .MUS. In greater detail, for each format, CD-Box follows these rules: o If there is a section about this format in CD-BOX.CFG ([<format>]), then CD-Box will provide external support, and: o If there is a "Dual=yes" statement in the section, and CD-Box has internal support for this format, then CD-Box will first try playing such songs using its own routines, and, if this fails (error while loading or whatever), use the external player. o If there is no such statement in the section, then CD-Box will ALWAYS use this player to play the song, using the parameters given in CD-BOX.CFG. o If there is no section on this format in CD-BOX.CFG, then CD-Box will use its internal routines to play the song, if any. o In all other cases, CD-Box will NOT play songs of this format (the corresponding pilot light above the song names is greyed). Usually you'll want CD-Box to play songs by itself; it's by far the easiest way, there's no player to install, and you can pause, resume and stop the song using the mouse. However, you would use an external player if: o CD-Box provides no internal support for the corresponding format CD-Box v3.03 Page 19 o Or you have a player capable of playing the format on your card, other than a SoundBlaster (for instance, a player capable of playing .CMF files on the AdLib). Note that even if CD-Box does have internal support for some formats, it may still need the corresponding driver. CD-BOX.CFG, CD-Box's configuration file, is explained page 22. _________________________________________________ 5. Details on .ARC, .ARJ, .PAK and .ZIP archives CD-Box is able to look into .ARC, .ARJ, .PAK and .ZIP files (hereafter called "archives") to see if there are any songs there; if it finds any, the corresponding title will appear on the main screen, and the song will be treated just as any other song. This means your songs can be packed in archives in CD-Box's directory to save space; CD-Box will find them anyway. _____________________________________________________________ a. When does CD-Box uncompress the songs stored in archives? Unpacking occurs in two cases only: o at startup, if a song found in an archive is not known to CD- Box, it will exploded using the appropriate archiver (ARCE.COM, ARJ.EXE, PAK.EXE, PKUNZIP.EXE, or whatever you specified in CD-BOX.CFG) so it can be analyzed. The program will try to extract the most information from the file (title and length in particular); the "Analyzing song" indicator is lit up. When done, CD-Box will remove the unpacked file. o just before playing a song stored in an archive, the small "CD- BOX" on the green reader at the top of the screen lights up and CD-Box invokes the archiver to explode the song file, and the bank file if necessary. When done playing, the unpacked files are removed also. ________________________________ b. Where are files exploded to? Files temporarily extracted from archives files reside on: o the drive/directory specified by the Temp= statement in CD- BOX.CFG; o if Temp= is not specified, the drive/directory specified by the TEMP environment variable; o if TEMP doesn't exist, to the default drive/directory. Always make sure there's enough room to hold the largest expanded song! Otherwise you'll get an "Unable to explode song" message. _______________________________________________________________________ c. What programs are necessary to take full advantage of this feature? Any programs capable of extracting files from .ARC, ARJ and/or .ZIP files (typically ARCE.COM, ARJ.EXE, PAK.EXE and PKUNZIP.EXE, but you might have others). If you don't have the corresponding archive manager, or if it is not reachable through a PATH statement, and if you have archives in CD-Box's directory, the message "Unable to explode song" will appear. The bottom line: using archives with CD-Box is pretty easy and straightforward. In the case of synthetized music files (.CMF, .MID, .MUS and .ROL), it also saves an average of 80% of disk space. And if you CD-Box v3.03 Page 20 archive your music files by category, you'll better take advantage of Files mode. Believe me, it's worth it!!! ________________ 6. Dual support .CMF, .MOD, .ROL, .VOC and .WAV files: it means CD-Box can play this format by itself. So you have three choices: o The easiest: just let it play the songs and don't worry about anything else. o If CD-Box won't play this format on your particular computer, you can try overriding its routines by telling it to use an external player (ex: AdLib users might have a .CMF player that works on their card). You simply have to insert the appropriate statements in CD-BOX.CFG. o CD-Box can also use both: try playing the format by itself, and if that fails, use an external player; you have to insert whatever is needed to run the player in CD-BOX.CFG, and add a "dual=yes" statement. See page 25 for how to tell CD-Box to use internal, external, or dual support. CD-Box v3.03 Page 21 E. KEYBOARD COMMANDS CD-Box can be used without the mouse entirely, although it was intended from the start to run with a mouse. In fact, versions up to v2.10 (inclusive) required a mouse; it was not optional. Some random animations lose much of their interest without a mouse; sometimes a grey arrow will appear to simulate the mouse, as in the "lighter" animation. The keyboard is active even with a mouse. What CD-Box does when a key is pressed is find which button to activate, then simulate a left button click. Most buttons can be clicked on by pressing their first letter, the notable exceptions being Rewind and Forward, which are PgUp and PgDn, respectively. The long rectangular button under the main button menu work the same, but with the Alt key held down. The volume, skip and echo controls work with the Ctrl key held down. The exact keys to click on the various buttons are on the back of this manual (last page). CD-Box v3.03 Page 22 F. CD-BOX.CFG _____________________________ 1. The purpose of CD-BOX.CFG CD-BOX.CFG is a file in which you can define many of CD-Box's parameters. Mainly, you can specify what driver/player programs to use, and also how to extract songs from archives, and various other things. CD- Box has default values for most of these parameters, but you can override them with CD-BOX.CFG. Two important remarks: o Errors in CD-BOX.CFG are skipped; CD-Box will simply give a warning message at startup and go on anyway. But these errors may hinder CD-Box when extracting or playing songs. A complete error report may be obtained by typing CD-BOX/D; the messages displayed are usually clear enough for you to understand what's wrong, and correct the situation. o Archivers run as subshells by CD-Box (and players if possible) must produce NO OUTPUT OF ANY KIND. The reasons, I think, are obvious (CD- Box runs in VGA and it wouldn't do to have big ugly characters messing up and maybe scrolling the screen each time you play a song). Therefore, make sure the archivers and player programs won't print anything, either using a parameter from the archiver or the player itself (for instance, /Q or - q), or by redirecting output to null, void, nothing, emptiness (> nul). This last solution doesn't always work; check under DOS. You might have a player which always displays something, or which you WANT to display something (for instance WOWII or PLAYROL); in this case, use the "text=yes" command described on page 26. __________ 2. Syntax ____________ a. Comments All blank lines and everything after a semicolon (;) are ignored. ______________________ b. Parameter settings Most parameters are set by typing the parameter name, an equal sign (with no space before nor after), and the parameter value. For instance: Temp=D:\ player=PLAY.EXE Case is not important in the parameter name, but it may be in the value; "/q" and "/Q" might not mean the same thing to a player program. CD-Box always preserves case when passing parameters to the programs it runs, except for filenames, which are always in uppercase. CD-Box v3.03 Page 23 _______________________ c. Section identifiers Some commands like Player=, Parameters=, and so on, need to know which format you're referring to. Special lines like: [ROL] means the following parameter settings are intended for the .ROL format. You can have a different section for each song format, and each archive format. _____________________ 3. Command reference _____________________ a. System parameters MixingSpeed=n This will set CD-Box's .MOD playing routines to n Hz per second. Lower values will run better on slower computers, while higher values enhance playback quality. Values higher than 22000 Hz don't make much sense since instruments in .MOD files are sampled at a rate of 22 KHz anyway. The default is 15909. This affects .MOD files only. MODDevice=n This set the output device .MODs are played to, n being: 0 PC speaker (sounds awful under CD-Box) 1 D/A converter on LPT1 2 D/A converter on LPT2 3 D/A converter on LPT3 4 D/A converter on LPT1 and LPT2 (stereo) 5 D/A converter on LPT1 and LPT2 (mono) 7 SoundBlaster card 10 Stereo-on-1 card 11 Disney Sound Source on LPT1 12 Disney Sound Source on LPT2 13 Disney Sound Source on LPT3 255 No sound (indeed not very useful) Default is 7 (SoundBlaster). This affects .MOD files only. CD-Box v3.03 Page 24 DefaultBNK=fichier Without this parameter, CD-Box supposes .ROL files it encounters for the first time need the BNK974.BNK bank file. This command sets this default to another bank file (for instance, STANDARD.BNK or COUCOU.BNK). Don't specify the extension, CD-Box will automatically add .BNK. This affects .ROL files only. Use this command to set the bank file you use the most often. If a few .ROLs need a different bank file, use the Modify mode. Temp=chemin This sets the path on which files extracted from archives temporarily reside. Make sure it's big enough to hold your largest song (and its bank file if necessary). If omitted, the temporary path defaults the current directory (or the directory in your TEMP environment variable). _______________________ b. Archiver parameters The only case you should have to insert commands like the following is if you have a different archiver than those I planned to handle .ARC, .ARJ, .PAK and .ZIP files. I put these commands in for completeness' sake, and just in case the upgrade to an archiver use a different syntax than the previous version (it's very unlikely but you never know). [ARC] archiver=ARCE.COM parameters=$zipfile $files /R /Q > nul This means the archiver for .ARC files is ARCE.COM, and when you extract the files "ABCD.TXT EFG.MOD" from the "HELLO.ARC" archive, you type at the DOS prompt: ARCE HELLO.ARC ABCD.TXT EFG.MOD /R /Q > nul $zipfile and $files are replaced at runtime by the appropriate names. $zipfile will always be a single filename (the name of the archive itself), while $files is a string of filenames separated by spaces (the names of the files to extract). Note that the "> nul" prevents ARCE from displaying anything on the screen, thereby preserving CD-Box's splendid graphics and stupendous animation (well, maybe I'm overdoing it a little... :-) The same things applies to all other archivers of course. If you use ARC.EXE instead of ARC.COM, insert the following commands: CD-Box v3.03 Page 25 [ARC] archiver=ARC.EXE parameters=x $zipfile $files > nul ________________________________ c. External drivers and players The syntax is very similar: [MUS] player=PLAY.EXE parameters=$song $bank This means the player necessary to play .MUS files is PLAY.EXE, and gives the parameters. $song is replaced by the song filename at runtime, and $bank by the bank filename (if any). If you start a song section, you HAVE to put in a Player= and a Parameters= command. There are four other song format-specific commands: dual=yes The simple fact that there is a song section in CD-BOX.CFG disables completely CD-Box's internal support for the corresponding format; it will rely entirely on what you specify as Player= and Parameters= to play the format. Specifying "dual=yes" re-activates internal support. When encountering a song of the corresponding format, CD-Box will first try to play it using its own routines; if this fails for a specific song, it will switch to external support, using what you put in CD-BOX.CFG. An example of how to use this follows on page 27. shell=yes Instead of running the player, CD-Box will run a COMMAND.COM that will itself run the player (COMMAND /C player parameters...). The advantage is that if the player is not very well written, COMMAND.COM will try to clean up the mess when shutting down and returning to CD-Box; the drawback is, of course, increased memory usage. Fortunately, such instances are rare, but SPUTROL, for example, leaves files open; when run many times without COMMAND.COM from CD-Box, it decreases the number of available file handles until nothing can be run anymore. If you use "> nul" to disable the player's output, you have to insert a shell=yes command so COMMAND.COM will take hold of the output and neutralize it. CD-Box v3.03 Page 26 swap=yes Before running the player, CD-Box will first swap itself and all its data into EMS memory; if not available, into XMS, or a temporary file on the path specified in the TEMP environment variable, or the current directory, in that order. The result is that instead of gobbling about 250 KB of main memory before running the player, CD-Box will use only about 5 KB, leaving all the rest to the player. An example of how to use this follows. text=yes CD-Box restore the video mode that was in effect at startup before running the player, and switches back to graphics mode when done. If you have a player which cannot run without displaying anything, or which switches to text mode, make sure you use this command; it guarantees CD- Box's display will not be messed up. Another example: [MOD] player=MP.COM parameters=-q $song dual=yes swap=yes If CD-Box cannot play the .MOD, it will run (dual=yes) an external player (player=MP.COM) using the indicated parameters (parameters=...), freeing beforehand almost all of main memory and relocating itself somewhere else (swap=yes). The explanation: if CD-Box tries to play a huge .MOD that does not fit in memory, the internal routines will fail (giving a "Out of memory" message); CD-Box will then free almost all of main memory, and run MP.COM, which will have about 600 KB on a 386 or better (560 KB on a 286) to load and play the .MOD file. Other .MOD players include ModPlay Pro, TrakBlaster, ProMod, WOWII, NFP and DMP. For instance, if you love WOWII, use the commands: CD-Box v3.03 Page 27 [MOD] player=WOWII.EXE /B:31000 parameters=$song /S swap=yes text=yes __________________________________ d. Support for other song formats CD-Box can support any number of song formats. All extra formats are considered as ".XXX" on the screen, but in fact the .XXX may be any extension. All you have to do is insert in CD-BOX.CFG a section just like the ones above. For instance, if you want to add .IMF support to CD-Box (Apogee's Monster Bash songs were released before the game as .IMF, a proprietary format), simply insert the following in CD-BOX.CFG: [IMF] player=PLAYIMF.EXE parameters=$song > nul You can add as many formats as you wish; examples include .NST, .STM, .669, .SND, .AU... whatever. The formats that become really widespread will be included in future releases of CD-Box, but in the meantime, or if you happen to like a very specific format, go ahead, CD-Box will be able to use it. As an aside, extra formats added like this do not have to play on your sound card. If you have MIDI equipment connected to your computer, and have an adequate player, CD-Box can run it! CD-Box v3.03 Page 28 G. ADVANCED USE ___________________________ 1. Command-line parameters CD-BOX/? gives you a quick summary. Otherwise, here are the details: o filespec: instead of scanning the entire directory, CD-Box will scan only the files matching your file specifications. For instance, if you want CD-Box to load the .MUS and .ROL files only, type CD-BOX *.MUS *.ROL; or if you just got a brand new archive containing new songs called ALLNEW.ZIP that's in drive A:, and you want CD-Box to scan only that archive, type CD-BOX A:ALLNEW.ZIP. An alternative is to use Files mode (see above). The default for filespec is, of course, *.*. o /D: This is a debugging tool which displays everything that happens as CD-Box is starting up. Check page 34 for a complete description. o /F: All non-essential animation is skipped, including the title screen, CDs popping up and down, buttons flipping over, .MOD level bars... o /H: Specifies which file CD-Box should display when F1 is pressed. The default is CD-BOX.DOC, French users use FRENCH.DOC. o /L: Tells CD-Box NOT to load the song formats which cannot be played (i.e. a driver is not loaded or missing or a player program is missing). In other words, CD-Box does not load songs which corresponding pilot light is greyed. This includes archive files; they will not be scanned if the corresponding archive manager cannot be found. o /M: Tells CD-Box not to use a mouse, even if it is able to detect one. This will remove the warning that no mouse is detected if none is present, and also will enable you to use the keyboard without having your mouse wrecking havoc on the screen, if your mouse driver is one of those which CD-Box doesn't like. o /O: Calls up the registration screen. This is the same as pressing "Register" within CD-Box. For prompt registration, please use the form printed by this screen. o /P: Loads CD-Box, plays n minutes of music by switching to Random mode, and then exits back to DOS upon completion of the last song. If Esc is pressed between songs, playback interrupts just as usual, and normal operation is resumed: you can then use the mouse to choose songs, change titles... o /R: Removes the files specified on the command line from the external database (SONGS.DAT). You have to specify the filenames (wildcards accepted), not the song titles. For instance, to remove the files IMPACT7.MOD and all Z*.ROL from SONGS.DAT, you would type CD-BOX /R IMPACT7.MOD Z*.ROL. CD-BOX /R would delete all the songs in SONGS.DAT it's CD-Box v3.03 Page 29 easier to erase the file. You shouldn't ever need to use /R, except in extremely rare cases where CD-Box would have fouled up and recorded a song length of 456324875 hours for a specific song... o /S: This tells CD-Box to also scan all the subdirectories it comes across. For instance, typing CD-BOX \ /S will scan the whole disk! o /V: Displays the contents (filename, bank filename, title and length) of the external database (SONGS.DAT) on the screen, pausing when the screen is full. The songs displayed match the file specifications on the command line default is (all). Blank entries in the Bank column indicate the file does not need any bank file, and blank entries in the Length column indicate the length of the song is not known (0). If you want to save this listing to a file, specify a filename, like this: CD-BOX /V=filename Output will be saved to the file filename.TXT. CD-Box v3.03 Page 30 H. TROUBLE-SHOOTING If you have a problem, don't hesitate to check out this chapter. CD- Box is very easy to use, but may be harder to install; the difficulties grow with the number of formats you use. But above all, don't panic; most problems have an easy solution. The first part in this chapter gives quick and easy solutions to most common problems. And the last part explains in detail how CD-Box scans archives and songs, so you can understand and solve the most tricky problems, especially if you try to modify CD-BOX.CFG. Also, if CD-Box crashes at startup, read this last part right now! ___________________ 1. Common problems ________________________________ a. Crashes during song analysis CD-Box hangs while "Building file index" CD-Box was trying to read a corrupted archive (.ARC, .ARJ, .PAK or .ZIP). Fix the archive or get rid of it! CD-Box stops with a "CRASH!" message and "ANALYZING SONG" was lit Type CD-BOX/D. CD-Box will display a lot of information you can ignore for the moment, and "CRASH!" again; however, this time the name of the faulty file is displayed on the screen. Follow these simple rules: o If it's while analyzing an uncompressed song ("Scanning" is displayed), it means the song has an invalid format, and CD-Box crashes when trying to extract meaningful values like song title and song length. Delete that song file! o If it's while opening an archive ("Opening" is displayed", the archive may be corrupted. Fix it! Page 34 provides more information on CD-BOX/D. _________________________________ b. Refusal to play certain songs CD-Box displays "Driver not found" .CMF: You're trying to play a .CMF file but you didn't load the SBFMDRV driver before starting CD-Box. Having SBFMDRV.COM on disk is not enough, it has to be loaded too. You can always unload it later on by typing SBFMDRV/U. .CMF: Same as above but with SOUND instead of SBFMDRV. CD-Box v3.03 Page 31 CD-Box doesn't play .VOC and .WAV files! If you do have a SoundBlaster card or compatible, it means CD-Box couldn't find it. You have to set the BLASTER environment variable. See BLASTER in the glossary (page 42) for how to do that. CD-Box displays "Player program not found" You have tried playing a song, and the associated player program was not found (the pilot light at the top should be greyed). Make note of the format causing problems, then run CD-Box with the /D parameter. If the corresponding program is displayed as "not found.", then you can't play these songs, unless: o You get the program and put it in CD-Box's directory, the directory from the SOUND environment variable, or somewhere on your PATH. o Or you modify the CD-BOX.CFG file to have CD-Box support another player you might have for that format. See page 22 for details. CD-Box displays "Don't know how to play" There's something wrong in the CD-BOX.CFG file. Either the player= or parameters= command is missing, and both must be present. Since CD-Box supports .CMF, .MOD, .VOC and .WAV internally, you can also remove the [CMF], [MOD], [ROL], [VOC] and [WAV] sections in CD- BOX.CFG (if there is one). This way, CD-Box won't try to look for external drivers and/or players, and will use its own code to play the songs. CD-Box doesn't play the song, and there is not error message This should happen only when you use an external player. If CD-Box acts as if it will play a song, but in fact doesn't play it at all, and no error is generated, it's because the player got an error (usually out of memory, but it could be corrupted bank file or something else), but reported none. CD-Box is then fooled into thinking everything was okay. Try playing the song by hand under DOS, and see what happens. If the player says a driver is missing (for instance ROLALARM wants the SOUND driver to be loaded in memory), then load it, and run CD-Box again. If there is no problem, then it's very likely the player ran out of memory - often the case with .MOD files above 250 KB, or with certain complex .ROL files. Add a "swap=yes" statement in the corresponding section in CD-BOX.CFG; CD-Box will swap itself in EMS, XMS or a temporary file, and leave all DOS memory free for your player (using only about 5 KB; without the "swap=yes", CD-Box uses about 250 KB). If this doesn't work for you, freeing DOS memory and loading resident programs high on 386+ computers (LOADHIGH SBFMDRV and things like that) is definitely a bonus, but not as drastic as swapping. CD-Box displays "Unable to explode song" Three possibilities (at least): o CD-Box can't find the archive manager necessary to extract the song from a .ARC, .ARJ, .PAK or .ZIP archive (run CD-BOX/D to find out). CD-Box v3.03 Page 32 Either make it available to CD-Box, remove any archives containing songs you may have in CD-Box's directory, or run CD-Box with the /L switch. o There isn't enough room on the temporary drive. o .MUS and .ROL only: there is another possibility: CD-Box has not found the bank file or could not explode it. Try changing the name of the bank file associated to the song (using Modify mode), or if the name is okay, check that it is in the same directory or archive than the song. CD-Box displays "Bank file not found" Bank files associated to each song must reside in the same place than the song itself; both must be in the same directory, or the same archive. For instance, if you have three different .ZIP archives of .ROL files, you must have all bank files used by these songs in each of the three archives. ______________________ c. Trouble with .MODs CD-Box displays "Invalid format" CD-Box recognises only 31-instrument .MOD files; you may have .MODs it won't play even though players like ModPlay do. There are two solutions to this: o Use an external player to play .MOD files, either overriding completely CD-Box's routines or using dual support (giving CD-Box a chance to play the song and telling it to use the external player if it can't). See page 22. o If you have ModEdit (or maybe another .MOD editor), load and save the .MOD files. ModEdit will always save the song as a 31-instrument .MOD, so it will be playable by CD-Box. .MOD files sound terrible! Apart from using an external player, you can try changing the "MixingSpeed=" statement in CD-BOX.CFG. The higher the value, the better, but CD-Box's feedback will slow down accordingly while playing .MOD files and might even hang if you specify a value which is too high for your computer. The default is 15909 Hz which should give good results on computers fast enough; 10000 Hz is kind of okay on "slow" machines. I don't have enough memory to play .MODs Use an external player. Look at page 27 for how to play huge .MOD files (up to about 550 KB). CD-Box v3.03 Page 33 Clicking on "Pause" doesn't really pause! When a .MOD contains instruments that loop continuously, CD-Box may have trouble stopping it temporarily without killing it completely. Resume the song, and try to pause again a little later. On the other hand, whatever the .MOD, clicking on "Pause" is not instantaneous, some instruments may go on playing a few seconds before stopping, don't worry, it's normal. ____________________ d. Hardware trouble CD-Box crashes and displays "VGA Sprite Manager has run out of memory" The VGA Sprite Manager is a huge object responsible for animating sprites on the VGA screen, not messing up the background, being able to superpose different sprites on different planes, and preventing flicker. However, it also needs a lot of memory; 64 KB + the sprites to move, so it usually amounts to about 80 - 90 KB. You can check the free memory by clicking on the "About" button. If you don't have enough, use the /F switch. The animations will be skipped, and the Sprite Manager will not be invoked. But chances are you're too short on memory to play some songs anyway. CD-Box returns suddenly to DOS and displays "CRASH" Well, if CD-Box wasn't analyzing a song, you stumbled on a bug. I left all the checking routines on in CD-Box's code, so that instead of hanging up and forcing you to reboot, it exits to DOS (in most cases). Restart CD-Box and try not to do it again - if you use CD-Box normally, you shouldn't get any bug. It's when you try to insist (for example, a .MOD song might not play because of insufficient memory, so don't try clicking on the song button 10 times to try to play it anyway), that CD-Box crashes. I, of course, am trying to get the number of bugs to an absolute minimum (very close to zero). CD-Box crashes and displays "Not enough memory to..."! You have a fatal memory overflow. You have to free more memory; run CD-Box by itself under DOS, not as a shell from another program. You can also try typing CD-BOX /F at the DOS prompt, and if you can get to the main screen, you may be safe... but you may also be too short on memory to play songs anyway. No music format works with my sound card! I have a SoundBlaster v1.50 so I'm sure CD-Box runs with this card. Above versions should work, as well as any SoundBlaster compatible card - it runs on the AdLib (.MUS and .ROL), and net users report it works with the SoundBlaster Pro (version 1 and 2) and the PAS-16. However, a net user reported it didn't work with his SoundBlaster v1.05. Maybe the use of CD- BOX.CFG can solve this problem, but nothing is guaranteed - I have no way to test that. CD-Box v3.03 Page 34 I have trouble with my mouse! YOU SHOULDN'T. Previous versions of CD-Box (up to v2.02) did have problem with furry creatures, but not since v2.10. CD-Box assumes the mouse is 100% Microsoft compatible (200% compatibility or more preferred). Some workarounds are changing the driver, or even changing the clock speed (turbo or non-turbo speed - weird, huh?). If CD-Box definitely cannot swallow your driver, use the keyboard (see page 21). Use the /M switch to remove mouse support entirely and not have the mouse pointer wreck the screen. That darn program doesn't work AT ALL! Read the license if you haven't already done so. I CANNOT GUARANTEE CD-BOX WILL RUN ON YOUR PARTICULAR COMPUTER. Let's be reasonable: I cannot guarantee this program will work for you. You MUST have a VGA display and a lot of free RAM (at least 500 KB, 550 KB better; if you don't have 640K conventional memory, forget it - but then who doesn't these days?). This is the very minimum configuration under which CD-Box will run. If you want to hear the songs, you need an AdLib Music Synthetizer Card or a SoundBlaster card (CD-Box does run, but is of absolutely no use without a music card). And if you have a lot of songs, you need (a little) more memory, too, of course. CD-Box was developed on a 286 up to v2.11, then on a 386, and net users didn't report any problems with their 486s; a 8086 might be slow, though. If you have a 8086, you should try the /F switch. _______________________ 2. Debugging switch /D If CD-Box doesn't play a specific music format, says it cannot explode songs from specific archives, or crashes at startup while analyzing songs, the "first-aid" procedure is to type CD-BOX/D. Chances are you'll find what's wrong. Okay, let's go. Here is an example of what CD-BOX/D can display: C:\SB\CD-BOX>cd-box /s c:\music\ a: /d CD-Box v3.03 - (C) Copyright Jeffrey Belt, 1993 - All rights reserved CD-BOX.CFG: ok. [I] .CMF driver: SBFMDRV not resident! [E] .IMF player: ok (C:\SB\PLAYIMF.EXE). [E] .MID format: don't know how to play! [I] .MOD format: ok. [D] .MOD format: ok (C:\SB\MP.COM). [E] .MUS player: ok (C:\SB\PLAY.EXE). [E] .ROL player: player not found! [I] .VOC driver: ok (port 0220H, IRQ 7). [I] .WAV driver: ok (port 0220H, IRQ 7). -> available formats: .IMF .MOD .MUS .VOC .WAV .ARC manager: not found. .ARJ manager: ok (C:\COMPRESS\ARJ.EXE). .PAK manager: ok (C:\COMPRESS\PAK.EXE). .ZIP manager: ok (C:\COMPRESS\PKUNZIP.EXE). Temporary drive/directory is: D:\ Building file index... done: 25 files found in 7 directories. CD-Box v3.03 Page 35 Scanning C:\SB\CD-BOX\VOC\BEACHBYS.ARC\409.VOC... archiver not found! Scanning C:\SB\CD-BOX\VOC\BEACHBYS.ARC\SURFUSA.VOC... archiver not found! Scanning C:\SB\CD-BOX\MOD\BONGO.ZIP\BONGO.MOD... exploding... error 1! Scanning C:\SB\MODEDIT\CREATION.MOD... DUPLICATE, ignored 25 song(s) scanned. Don't worry, this example has been chosen because it contains many error messages. Usually there are much less. Note for starters that you can (and should) give all the parameters you usually use as you run CD-BOX/D. The information displayed is divided in several categories, which match exactly the different steps of CD-Box's startup. Let's look at them: 1. Loading of the configuration file CD-BOX.CFG. If this file has errors, messages and line numbers are displayed; these messages are described in the CD-BOX.CFG chapter. Otherwise, if CD-Box understood everything, "ok" is displayed, as in our example. 2. Activation of the music formats. CD-Box displays the status of each format, with an [I] for internal , [E] for external, and [D] for dual support. If everything is okay for a format, "ok" is displayed, otherwise one of several error messages is displayed. These messages are precise enough to enable to quickly find the cause of the error, but are extremely numerous, so I won't explain them all here. The errors in our example are the more frequent; to solve them, you have to: o .CMF: load the SBFMDRV driver before running CD-Box (type SBFMDRV or LOADHIGH SBFMDRV at the DOS prompt). o .MID: CD-Box has not internal support, and expects instructions in CD-BOX.CFG. But it can find no command relative no the .MID format (there is no [.MID] section, or the Player= or Parameters= command is missing), so CD-Box doesn't know how to play this format. The solution: find a .MID player, and insert the appropriate commands in CD-BOX.CFG. o .ROL: CD-Box couldn't find the player specified in CD-BOX.CFG, either because its name was misspelled, or because it indeed isn't on disk. Check the spelling of the filename given in the Player= command, and make sure the player is in the PATH, or in the directory specified in the SOUND environment variable. Since CD-Box has internal support for .ROL, you can remove the [ROL] section from CD-BOX.CFG anyway. Now that you know that, do whatever you want, it's your computer. o All other formats: no problem. CD-Box also displays a summary of available formats: .IMF .MOD .MUS .VOC .WAV. Two remarks: o Two messages are displayed for the .MOD format; it's because there is a "dual=yes" command in the [MOD] section of CD-BOX.CFG. One message is for internal support [I], and the other for dual support [D]. o .IMF is not a format CD-Box supports by default, but it is treated as any other once you've added the CD-Box v3.03 Page 36 appropriate instructions in CD-BOX.CFG. See page 27 for details. 3. Activation of the archive formats. CD-Box does the same thing for archivers; if one is not found, "not found" is displayed. In our example, if you don't use .ARC archives at all, there is no problem; otherwise, make sure the archiver is somewhere on the PATH. Or, if you have an archiver different than the one CD-Box looks for, insert the appropriate commands in CD-BOX.CFG. 4. File index building. There seldom are errors here, CD-Box displays the total number of files found. 5. Song index building. This is the "heart" of CD-Box, so we'll delve into this in detail. The song filenames flash quickly while they are scanned. When CD-Box scans an archive, it opens it ("Opening"), then scans the songs within ("Scanning"). If the song is known, it is simply stored in the index and the search goes on. On the other hand, if the song is not known, CD-Box has to analyze it, to extract data like title, length, and bank file; and this is where errors can happen. Let's start with the worst case: CD-Box displays: Scanning C:\SB\CD-BOX\ROL.ARJ\ZULU.ROL... * CRASH! * 100/1351:075A * Possibles causes: - corrupted song (type CD-BOX/D and see if the error repeats itself) - memory overflow Otherwise see "Trouble-shooting" in CD-Box's documentation. The file CD-Box was analyzing is corrupted. Delete it! The advantage of CD-BOX/D is that the faulty filename remains on the screen (in our case, ZULU.ROL). If the message displayed is: "Opening C:\SB\CD- BOX\ROL.ARJ..." for instance, it's archive ROL.ARJ's fault. The command ARJ t ROL.ARJ would undoubtedly report a corrupted archive. Fix it or delete it! This case is the worst, and stops CD-Box completely. In the vast majority of cases, CD-Box displays a warning message, and goes on. These warnings are: archiver not found! The song is stored in an archive CD-Box can read, but not extract, because the archiver is missing. Make sure the archiver is on the PATH, or extract the song, and store it in another type of archive if you want to. exploding... failed! CD-Box ran an archiver to extract a song, which terminated without reporting any error, but CD-Box realized the song has not been extracted at all. In most case, it's because the archiver got an error (usually disk full, but it might be because the song is password-encrypted), but didn't report any. Change the value of Temp= in CD-BOX.CFG! CD-Box v3.03 Page 37 exploding... error n! This warning is like the previous one, but this time the archiver did return an error number n. Refer to the documentation of the archiver to understand the problem. DUPLICATE, ignored. CD-Box already encountered this song while scanning. It is a simple information message, CD-Box will only remember the first occurrence in any case, but you can remove one of the duplicated from your disk. CD-Box v3.03 Page 38 I. REGISTERING CD-BOX CD-Box is shareware. The registration fee is $20. ______________________ 1. What is shareware? Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- CD-Box in particular specifies a maximum 30-day evaluation period. With registration, you get the right to continue using the software and usually something extra (bound manual, extra programs, etc). With CD-Box, the registration reminders are removed, and you get the latest version and extra programs (more on this later). Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. The terms for CD-Box are in the VENDOR.DOC file. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. _________________ 2. Why register? Because it's the right thing to do. You wouldn't want to break the law, would you? You are encouraged to use and copy this program and give it to your friends for a 30-day evaluation period. Once this period has expired, you have to register the program. The registration fee is $20 US dollars. In return, you'll get: o a registration key and instructions to remove the registration reminders using this key. This key will be valid for all CD-Box v3.xx versions. o a diskette containing: o the latest version of CD-Box (or the next version if it is almost ready to be released). I'm still under the shock of receiving yesterday a registration form for CD-Box v2.11 which I released more than a year ago! For examples of things to come, see the HISTORY.DOC file. o a menu-driven SETUP utility to easily modify CD- BOX.CFG (without using a text editor and dirtying your hands in ASCII). CD-Box v3.03 Page 39 o the full documentation in English and French. o third-party software that I find of value to sound card owners in general, and to CD-Box users in particular. o and as many song files as will fit. o mail or phone support (see below). o a six-month "I fix the bugs or your money back" guarantee (see below). o notification by letter of the next major update. o and, of course, discounts on future versions of CD-Box (v4.00 and above) and my other products. I'm also thinking of printing this manual, and if I do print it and you showed interest (see registration form), I'll notify you, and make it available to you at the rock-bottom price. If some of these products become unavailable for distribution, other products which have value to sound card users will be substituted. Some of these products may be shareware and require you to pay a registration fee after an evaluation period. __________________________ 3. How to register CD-Box The registration fee is $20. If for some reason CD-Box is discontinued, I'll send your money right back with an explanation. US dollars are used for convenience; ANY currency will do, as long as it amounts to the same sum in US dollars; take bank commission into account. See the registration screen for examples. To register you, I need either cash or a check (made to the order of Jeffrey Belt), and an order form. Press F2 within CD-Box to display the manual, then press R; or type CD-BOX/O at the DOS prompt. This will call up the registration screen. Just fill it in and choose your output device: printer (specify the port) or file (INVOICE.TXT). If you don't have a printer, print the order form in the INVOICE.TXT file, and print this file on a friend's or neighbour's printer. Better yet, give him CD-Box to print your order form! If you REALLY don't have access to a printer, write on a piece of paper, a postcard, or something else: o which version of CD-Box you've got (press the "About" button in CD-Box). o your first and last name (without which I cannot give you a registration key). o your full mailing address. The rest is optional: CD-Box v3.03 Page 40 o where you got CD-Box (which server, BBS, company...). o your remarks and suggestions (if any). Send the filled-in order form and payment to: Jeffrey BELT 2A Crothers Hall Stanford, CA 94305 U.S.A. My phone number is (415) 497-5573 in the United States. If you have net access, my e-mail address is belt@cs.stanford.edu. All this is valid until December 15, 1994. Do NOT send registration forms to this address after this date! If you can't find an updated version of CD-Box with my new address in it, please either: o write or call the ASP and they will tell you how to reach me, or o send a postcard to the following address asking how to reach me: Jeffrey BELT 7 rue de la Garenne 77240 - CESSON FRANCE ___________ 4. Support If you experience difficulties with CD-Box, then write, call, or e- mail. The same applies to suggestions for improvement. I always answer all the mail I receive, priority being given to registered users for a minimum period of six months after the date of registration. So don't hesitate! New versions of CD-Box are uploaded on saffron.inset.com and SIMTEL, and sent to a growing number of vendors; update announcements appear in the Sound Newsletter (available on BBS and FTP servers worldwide and posted in particular to comp.sys.ibm.pc.soundcard). Major updates will also be sent to the ASP vendors. ____________________ 5. Bugs? What bugs? As far as I know, this program is free of bugs. In any case, it does not contain any intentional bugs. But I also know no significant software has ever been produced without bugs lurking around. If you find any, TELL ME in detail! There's no chance of the bug being corrected if I don't know about it! Bugs will be fixed for free for six months following registration, if possible. If not, a full refund will be offered. When reporting a bug, please be as precise as possible. What version number of CD-Box are you using? What exactly were you doing when the bug happened? What are the exact symptoms? I received in the past bug reports about mice for CD-Box v2.02 and below, like "my mouse goes crazy" or "doesn't work"... how am I supposed to work on this?!? It was by asking for details that I finally knew "the yellow mouse seems to be at double the position of the white mouse", and "random colored points are sprayed around the mouse arrow", and so the trouble was fixed. Don't forget to include a full description of your hardware and software environment so that I can try to duplicate the problem. CD-Box v3.03 Page 41 ______________________________________ 6. Viruses and similar nasty programs I guarantee that the copies of CD-Box I send on diskettes to vendors and distributors are virus-free. However, bear in mind the copy you have may have been infected, unwittingly or not, by someone else. Most, if not all, vendors and distributors check again for viruses, so the odds are low, but you never know. The odds get higher as your source becomes more "doubtful" (i.e., the copy of a friend of a friend of a friend...). CD-BOX.EXE contains verification code to protect itself at each startup against viral attacks or hacks. It does not protect your system against viruses or other similar programs, nor does it guarantee for sure CD-Box is not infected. However, if CD-Box detects a modification of its code, it will stop and display the following message: This program has been corrupted or modified. Please restore it from a safe backup copy. You must then make a fresh copy of CD-BOX.EXE from the original or a safe backup copy. CD-Box v3.03 Page 42 J. GLOSSARY Entries are not in logical order, but in alphabetical order. Inexperienced users may want to read the "driver", "player" and "environment variables" entries first. ARCHIVER An archiver is also called archive manager, compressor, compactor, of files or archives. It is a program able to store in one file (the archive) many different files, shrinking them so they use less space on disk; the opposite operation (extraction) is of course possible. The most widespread formats are .ARC, .ARJ, .LZH, .PAK, .ZIP and .ZOO, and are common use on file servers (BBS, FTP, and others). Each archiver has its own commands, so see the documentation of each to see how to use them. BLASTER BLASTER is an environment variable you can use to tell CD-Box where your SoundBlaster card (or compatible) is located. To set it, type: SET BLASTER=Axxx Ix Dx Tx Axxx is the port, usually A220 for port 220H (factory default). Possible values are A210, A220, A230, A240, A250 and A260 (the SoundBlaster Pro accepts A220 and A240 only). Ix is the interrupt line (IRQ), for instance I3 for IRQ3. Possible values are I2, I3, I5, I7 and I10. Dx is the DMA channel, usually D1 for DMA channel 1. The "plain- vanilla" SoundBlaster is always on DMA 1, but possible values for the SoundBlaster Pro are D0, D1 and D3. Tx is the card type. T1 is for the SoundBlaster v1.0 and v1.5, T2 is for the SoundBlaster Pro, and T3 is for the SoundBlaster v2.0. I have for instance a SoundBlaster v1.5 on port 220H and interrupt line IRQ7. My AUTOEXEC.BAT contains the following line: SET BLASTER=A220 I7 T1 D1 CD-Box uses the settings provided by the BLASTER environment variable (port and interrupt only, it ignores the other two). If BLASTER does not exist, it will try to locate the card by itself, but may not be always successful. I highly recommend the use of BLASTER, since CD-Box and many other software use this variable. DRIVER A driver is a program, whether resident (SBFMDRV.COM) or not (CT- VOICE.DRV) that allows the programmer knowing how to "talk" to this driver to control something more or less easily - in the case of the CD-Box v3.03 Page 43 SoundBlaster, to play files without going down too much into the details of the file formats, memory or the card itself. One driver can be used by several programs (for instance, a printer driver in Windows is used by all Windows software so they don't have to worry about the details of the printer). ENVIRONMENT VARIABLES DOS enables you to define variables, or symbols, and to store values in these variables. All programs can afterwards use these variables you define. The syntax is: SET variable=value Variable must be a single word, with no space or other separator. Value, on the other hand, can be a string of (almost) any characters. You can display all variables that have a value in your system by typing the SET command with no argument. SET for can instance display: COMSPEC=C:\DOS\COMMAND.COM PROMPT=$p$g PATH=C:\DOS;C:\DOS\UTIL;C:\COMPRESS;C:\CD-MENU;C:\SB;C:\DOS\F-PROT SOUND=C:\SB TEMP=E: (It will look different on your computer.) Four environment variables have a specific meaning for CD-Box: o BLASTER, to set the SoundBlaster port and IRQ. o PATH, where to look for archivers and players. o SOUND, where to look for players, if they weren't found in the PATH. The value of SOUND is normally a directory where SoundBlaster programs are stored (see the user's manual of your sound card). o TEMP, to know where to move when running the "swap=yes" command and there is not EMS nor XMS, and to know where to temporarily store extracted files, unless this command is specified in the "Temp=" command of CD-BOX.CFG. The value of TEMP should be a drive or directory where many software store their temporary files, preferably a RAM disk. FORMAT Computer files can contain extremely diverse data: text, graphics, sounds, programs, databases... The idea being to store data in a usable form, software usually defines "formats", that is, rules which say exactly how the data is to be stored in files. CD-Box v3.03 Page 44 The extension of a file usually gives an indication on its format. You surely know that .BAT, .COM and .EXE are executable files (programs), and .DOC and .TXT usually is readable text. In CD-Box, .CMF, .MID, .MOD, .MUS, .ROL, .VOC and .WAV are music formats (others exist!), and .ARC, .ARJ, .PAK and .ZIP are well-known archive formats (others exist too). Each software often defines its own format, which may (unfortunately) bear the same name of another software's format. A .MOD file is usually a song file, but Windows, for instance, has .MOD files that have nothing to do with music. When CD-Box displays "Invalid format", this means it thought the file contained a song, just by looking at the extension. But when it tried to use this file to play it, or to extract the title, it realized informations it expected to find at certain locations in the file were not there. So it displays "Invalid format" to denote a file which seemed to contain a song at first, but which doesn't after all. PATH The PATH is an environment variable which contains a list of directories separated by semicolons. When you type a program name at the DOS prompt, the program is searched in each of the directories specified in the PATH; if the program is not found, DOS displays "Invalid command or file not found" or something close. To display what's in the PATH, type the PATH command: PATH=C:\DOS;C:\DOS\UTIL;C:\COMPRESS;C:\CD-MENU;C:\SB;C:\DOS\F-PROT (It will look different on your computer.) So, in this case, if you type MEM, DOS will look on disk for the following files: MEM.BAT (or .COM or .EXE), C:\DOS\MEM.BAT (same thing), C:\DOS\UTIL\MEM.BAT, C:\COMPRESS\MEM.BAT... as soon as one such file is found, it is run, and the MEM program starts. CD-Box uses the PATH to look for programs it may need (archivers and players). If you say in CD-BOX.CFG that the [ZIP] format must be handled by the UNZIP.EXE program, CD-Box will look for in our example for the following files: UNZIP.EXE, C:\DOS\UNZIP.EXE, C:\DOS\UTIL\UNZIP.EXE, C:\COMPRESS\UNZIP.EXE... When you type CD-BOX/D, CD-Box displays the programs it found, with the full access path. If, on the other hand, CD-Box displays "not found", this means your program is not on the PATH, that is, not in any directory specified in the PATH environment variable. Put the program in the PATH, or change the PATH definition to include the directory where the missing program is. PLAYER A player is a program which is able to play songs in a specific formats (sometimes in more than one format, but that's rare); a player may need a driver to work. CD-Box is indeed a player, a multi-format player even, but is much more than that (interface, animations, handling of titles...). Better examples include VPLAY, PLAYCMF and ModPlay Pro. CD-Box v3.03 Page 45 K. EXTERNAL DRIVERS AND PLAYERS CD-Box uses by default the following drivers and players (you can change this if you modify CD-BOX.CFG, see page 22): Driver .CMF: SBFMDRV.COM - Creative Labs, Inc. Bundled with the SoundBlaster Player .MID: FORMER.EXE - comes with HOLYWOOD That's all I know. Give me more info if you have any! Player .MUS: PLAY.EXE No info on this one - got it from a FTP server which IT got from THE TASTE/MG BBS, 718-252-4529, as ADLIBMUS.ZIP. Driver .ROL: SOUND.COM - AdLib, Inc. (or next one) Bundled with the AdLib Driver .ROL: SB-SOUND.COM - Creative Labs, Inc. (or previous one) Almost no info on this one, but like SBFMDRV (and unlike SOUND), can be removed from memory. You can of course override CD-Box's internal routines with external players not quoted here (for instance, play .MODs with ModPlay Pro or WOWII, or .ROL with SPUTROL or ROLALARM or INTUNE). FTP addresses: saffron.inset.com, nic.funet.fi, snake.mcs.kent.edu, wmsr.simtel-20.army.mil. CD-Box v3.03 Page 46 L. TECHNICAL NOTES ___________________ 1. A word on files Two files are necessary for CD-Box to run: CD-BOX.EXE (the program itself, with all its code and graphics), and CD-BOX.CFG (the configuration file). CD-Box will create the SONGS.DAT file to store song names and lengths. If a player crashes, and you specified "swap=yes" in the corresponding section in CD-BOX.CFG, you may found on disk a CD-BOX.TMP file which you can delete. _________________ 2. Sound formats .MOD: CD-Box processes only 31-instrument .MODs, and only in mono. I'm working on 16-bit stereo! .ROL: CD-Box expects SOUND.COM v1.51 or later. It uses the extended waveform capabilities of the AdLib v1.51 or later and SoundBlaster v1.5 or later. .VOC: CD-Box processes block IDs 1 (sample), 2 (subsequent sample), 3 (silence), 6 (repeat) and 7 (end repeat). All other blocks are skipped. CD-Box sends the data to the DSP in real time rather than using the DMA, hence the volume and echo controls. .WAV: CD-Box makes an "on-the-fly" conversion and sends the whole thing to the DSP. Because of outrageous computing times, it is currently only able to process 8-bit mono samples. I'm working on the 16-bit stereo version... CD-Box v3.03 Page 47 M. THANKS CD-Box wouldn't be the program it is today without the help of the following people: o Programmers: Mark J. Cox (MODOBJ library to play .MODs), Victor Langeveld (precious help to solve mouse bugs), Anthony Rumble (sources to play .CMF), Thomas Wagner (EXEC function to move CD-Box to EMS, XMS, or hard disk when an external player is run; used when the "swap=yes" command is used in CD-BOX.CFG). o Enlightened users, for their good ideas: Ed Haymore (temporary drive redirection, and basic idea for Files mode), Bjorn Karlsen (keyboard support on volume control), Bob Mandel (a lot of helpful advice and a fascinating handwriting). o Sympathetic sysops: Dave Komatsu (Sound Newsletter Editor), and Keith Petersen (sysop of MSDOS archive on SIMTEL), for having accepted my submission! And many more thanks go to Dave for having uploaded CD-Box when I was not on the net. o Crazy about image synthesis: Stephane Marty (tremendous French ray-tracing software SMTRACER 386, which computed some of the screen graphics). o The others: Bruno Deltour (aesthetic remarks), Alain Rousseau (has provided me files from the net when I wasn't on it), Jean-Francois Moufle (has driven the car, now much reduced, driving across the screen at odd times) (yes, I drew all the other graphics, and no, I'm not an artist!), my sister (for rebuilding my morale when it sank low), my mother (still hasn't understood how I could be so addicted to computers but patiently endures it nevertheless), and various other friends and relations for having stumbled on the thankfully rare bugs, and for their suggestions and encouragements. And many thanks to the registered users of CD-Box which are the ones keeping it going! CD-Box v3.03 Page 48 N. LICENSE & ABSENCE OF WARRANTY ______________ 1. Disclaimer Users of CD-Box must accept this disclaimer of warranty: "CD-Box is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of CD-Box." This statement and the licence agreements below shall be governed by the laws of France. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a court of competent jurisdiction located in Paris, France. _____________________ 2. Trial use license The word "software" below refers to the freely available version of CD-Box, and in particular the three files CD-BOX.EXE, CD-BOX.CFG and CD- BOX.DOC. You are encouraged to use this software for 30 days prior to obtaining a permanent license. You may copy this software as many times as you like, give it to anyone, and distribute it via electronic means. This software may also be distributed in shareware and/or public domain libraries that charge for copying and distributing disks, NOT for the software itself. You may NOT charge or request a donation for a copy of this software, however made; and you may NOT distribute this program and/or documentation with commercial products without written permission from the author. THIS SOFTWARE MAY NOT BE GIVEN AWAY OR DISTRIBUTED WITHOUT ITS DOCUMENTATION; AND NEITHER PROGRAM NOR DOCUMENTATION MAY BE ALTERED IN ANY WAY. Users of CD-Box must register and pay for their copies of CD-Box within 30 days of first use or their license is withdrawn. Once the registration payment is made, the permanent license applies. If you do not agree to this license, delete CD-Box from your computer and don't send any money. _____________ What it means CD-Box is a "shareware program" and is provided at no charge (except shipping charge in some cases) to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system (don't give just the program, give also the documentation and extra files; if you modified CD-BOX.CFG for your personal use, take care not to distribute the modified version). The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using CD-Box and continue to use CD- Box after the 30-day trial period, you must pay the registration fee. _____________________ 3. Permanent license The word "software" below applies to the registration key and extra utility programs clearly marked as "This program is part of the CD-Box registration disk" on the disk received when registering (in particular CD-Box v3.03 Page 49 SETUP.EXE). Other third-party programs on this disk are covered by their own licenses. The $20 registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. By ordering a license, you acknowledge that the registration key is a trade secret and agree to protect it as such. This license is not transferrable and may not be modified. CD-Box v3.03 Page 50 AdLib Music Synthetizer Card is a trademark of AdLib, Inc. Also, SOUND.COM is copyrighted by AdLib, Inc. SoundBlaster is a trademark of Creative Labs, Inc. Also, SBFMDRV.COM is copyrighted by Creative Labs, Inc. ARCE Copyright (c) Vernon D. Buerg. ARJ Copyright (c) Robert K Jung. LZEXE Copyright (c) Fabrice Bellard. PAK Copyright (c) NoGate Consulting. PKUNZIP Copyright (c) PKWARE Inc. Other trademarks and products mentioned in this documentation are the property of their respective owners. The software and documentation are: (C) Copyright Jeffrey Belt 1993. CD-BOX V3.03 REFERENCE CARD _____________________________ All modes except Playing mode Help: F1, H or ? Manual: F2 ___________ Select mode Rewind: PgUp, left or up arrow, or Backspace Forward: PgDn, right or down arrow, or Enter Other buttons: Play (P), Loop(L), Random(R), Eject(E). ____________ Playing mode Stop: Esc (even if the button is not displayed) .MOD volume: Ctrl A (minimum) to Ctrl L (maximum) Forward, Echo+: Ctrl-right arrow Backwards, Echo-: Ctrl-left arrow Other buttons: Skip (S), Pause (P), Again (A), Rem (R), Total (T). ___________ Modify mode Rewind, Forward: same as above About: A or ? Other buttons: File (F), Bank (B), Title (T). __________ Files mode Rewind, Forward: same as above Rescan: R, Alt F or Esc _____ Songs 1 to 8 (1 to 4 in the first column, 5 to 8 in the second). ___________ Mode select Press Alt and the first letter of the mode (ex: Alt F for Files).